<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 24.2.1</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="24.2.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="24.2.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P4">Part IV. The C API</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#24">Chapter 24. An Overview of the C API</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h3>24.2.1 &ndash; Pushing Elements</h3>

<p>The API has one push function for each Lua type that
can be represented in C:
<code>lua_pushnil</code> for the constant <B>nil</B>,
<code>lua_pushnumber</code> for numbers (<code>double</code>),
<code>lua_pushboolean</code> for booleans (integers, in C),
<code>lua_pushlstring</code> for arbitrary strings (<code>char *</code>),
and <code>lua_pushstring</code> for zero-terminated strings:
<pre>
    void lua_pushnil (lua_State *L);
    void lua_pushboolean (lua_State *L, int bool);
    void lua_pushnumber (lua_State *L, double n);
    void lua_pushlstring (lua_State *L, const char *s,
                                        size_t length);
    void lua_pushstring (lua_State *L, const char *s);
</pre>
There are also functions to push C functions and userdata
values on the stack; we will discuss them later.

<p>Strings in Lua are not zero-terminated;
in consequence, they can contain arbitrary binary data
and rely on an explicit length.
The official function to push a string onto
the stack is <code>lua_pushlstring</code>,
which requires an explicit length as an argument.
For zero-terminated strings, you can use also <code>lua_pushstring</code>,
which uses <code>strlen</code> to supply the string length.
Lua never keeps pointers to external strings
(or to any other object, except to C functions,
which are always static).
For any string that it has to keep,
Lua either makes an internal copy or reuses one.
Therefore, you can free or modify your buffer
as soon as these functions return.

<p>Whenever you push an element onto the stack,
it is your responsibility to ensure that the stack has space for it.
Remember, you are a C programmer now; Lua will not spoil you.
When Lua starts and any time that Lua calls C,
the stack has at least 20 free slots
(this constant is defined as <code>LUA_MINSTACK</code> in <code>lua.h</code>).
This is more than enough for most common uses,
so usually we do not even think about that.
However, some tasks may need more stack space
(e.g., for calling a function with a variable number of arguments).
In such cases, you may want to call
<pre>
    int lua_checkstack (lua_State *L, int sz);
</pre>
which checks whether the stack has enough space for your needs.
(More about that later.)

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="24.2.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

